<rhq-install-dir>/bin/rhq-installer.[sh,bat] --reconfig
In the future, installing the RHQ Server may be performed differently as explained on this page. This is because future versions of RHQ may conform to the new Layered Distribution model of JBoss AS.
This is a brief page to explain the new installer mechanism to install the RHQ Server in an AS7 app server.
First, if you are installing on a UNIX/Linux machine, you now have the option to install the RHQ Server on top of an existing, previously installed, JBoss AS7. If you downloaded the AS7 installation and unzipped it in some external location (let's say /opt/jbossas7), you can set the environment variable JBOSS_HOME to point to that /opt/jbossas7 directory. You can also target RHQ to be installed on a specific AS7 installation by setting the RHQ_SERVER_JBOSS_HOME environment variable. RHQ_SERVER_JBOSS_HOME takes precendence; if it is set, it will be used; if it is not set, JBOSS_HOME will be used. If neither is set, RHQ will install within its own, internal AS7 that ships with the RHQ Server distribution (located at <rhq-server-install-dir>/jbossas). If you want to install in an external AS7, you can unzip the RHQ Server distro and exclude the internal AS install that comes with it (via the command unzip <distro.zip> -x '*/jbossas/**') or just "rm -r" the RHQ Server's jbossas directory.
If you are installing on Windows, you cannot install on a separate AS7 install and the JBOSS_HOME / RHQ_SERVER_JBOSS_HOME environment variables are ignored by RHQ. On Windows, RHQ will only be installable in the AS7 installation that comes with the RHQ Server distribution.
It is not the purpose of this feature to allow you to install inside an AS7 that has other applications deployed and running in it. The real reason why this feature exists is it is the start of an implementation to support RPM installations. It is planned for the RHQ Server distribution to be shipped in RPM form sometime in the future. This is why we are starting to implement ways to install the RHQ Server in an external AS7 install. The goal is to be able to install the RHQ Server via an RPM which, itself, has a dependency on an RPM-installed AS7 instance. This isn't supported today, but, the result of this work is that today you can install the RHQ Server in your own AS7 installation (for example, if you wish to manage that AS7 yourself and patch it yourself with AS7 bug fixes that could benefit RHQ).
It is still required that you run RHQ Server in its own dedicated AS7 instance, no matter where that AS7 instance is installed.
The second thing to note is that RHQ no longer has a GUI installer application. You install via the command line only. RHQ now ships with a script rhq-installer.sh that you will use to complete the RHQ Server installation. How to use this installer script is explained below.
If you are a developer, and have a dev build of RHQ, the installer will run automatically if you run "rhq-server.sh console" or "rhq-server.bat console" (on UNIX and Windows respectively).
You will also notice that the RHQ EAR is not hot deployed by the deployment scanner (that is, the EAR is not located in the app server's deployments/ directory). Rather, our EAR is deployed by our own custom AS startup extension and the EAR itself is found under <rhq-install-dir>/modules, not deployments/ (specifically, the EAR is found in our startup extension module).
If developers wish to hot-deploy changes to code, they can use the -Pdev maven module to copy the new artifacts to this modules location and then ask the app server to reload.
If you plan on installing with Oracle as the backend DB, you need to acquire the Oracle JDBC driver from an external source (due to licensing restrictions, RHQ cannot ship with the Oracle JDBC driver). Once you obtain the Oracle JDBC driver jar file, you must copy it to the <rhq-install-dir>/modules/org/rhq/oracle/main directory. You also must make sure the name of the jar matches that in the module.xml file located in the same directory (see the <resource-root> element's "path" attribute). Do this before running the server or installer.
If you do not plan on having an Oracle database, you don't have to do anything. A valid Postgres JDBC driver is included with RHQ out-of-box - Postgres should work without any customizations.
Here's a set of quick steps to install the RHQ Server. For more details steps, see the "Steps To Install" below.
Unzip the RHQ Server in some directory (to be referenced as <rhq-install-dir>)
Edit <rhq-install-dir>/bin/rhq-server.properties so all settings match your environment
Make sure you set rhq.autoinstall.enabled=true in rhq-server.properties.
Use <rhq-install-dir>/bin/rhq-installer.[sh,bat] --dbpassword=<your password> to encode your DB password for the value of the property rhq.server.database.password
Run the RHQ Server via <rhq-install-dir>/bin/rhq-server.[sh,bat]
Run <rhq-install-dir>/bin/rhq-installer.[sh,bat] to complete the installation
To install the RHQ Server:
Unzip the RHQ Server distribution into some destination directory (to be referenced as <rhq-install-dir>)
Load <rhq-install-dir>/bin/rhq-server.properties in a text editor and change all the settings so they are correct for your environment. You can leave many of the values as is, but you must ensure things such as the database settings, host and port settings are all correct for your environment. You can read the comments found in the properties file itself for more documentation.
The value of the property rhq.server.database.password must be encoded. Do not enter your actual database password here. Use <rhq-install-dir>/bin/rhq-installer.[sh,bat] --dbpassword=<your password> to encode your DB password for the value of this property.
Once you made sure all settings in rhq-server.properties are correct, you must make sure you set the rhq.autoinstall.enabled property to true.
Run the RHQ Server
If you are on UNIX/Linux:
If you want to install RHQ in an external AS7 installation, make sure you set the environment variable JBOSS_HOME or RHQ_SERVER_JBOSS_HOME appropriately. It must point to the installation directory of your existing AS7 installation. You can skip this step and not define those settings if you just want to use the AS7 that ships with RHQ (which is what you normally want to do anyway).
Start the server via <rhq-install-dir>/bin/rhq-server.sh console
If you are on Windows:
Start the server via <rhq-install-dir>\bin\rhq-server-console.bat
Run the RHQ Installer script
You can validate your setup without actually installing. If you pass in the command line --test (or -t) to the rhq-installer script, it will perform some validation and output information to the console indicating if everything is ready for performing the installation.
If you are on UNIX/Linux:
<rhq-install-dir>/bin/rhq-installer.sh
If you are on Windows:
<rhq-install-dir>\bin\rhq-installer.bat
Once the installer script completes, your RHQ Server will soon be ready. No further work needs to be done.
The steps to upgrade are virtually the same as the steps to install as documented above. There are some things to note if you are upgrading:
Make sure you shutdown the RHQ Server you want to upgrade.
Make sure you keep a backup copy of your old RHQ Server's rhq-server.properties so you can refer to the values previously used. You will probably want to make most, if not all, values you have in the old properties file to be the same in the new.
If you made customizations to the old bin/rhq-server-env.sh (if on UNIX/Linux) or bin/wrapper/rhq-server-wrapper.conf (if on Windows) files, back them up because you will need to reapply those changes manually. Note that you rarely, if ever, have to modify these files, so you probably don't have to worry about this step.
Do not extract the RHQ Server distribution over top the old RHQ Server distribution you are upgrading. Either extract it in a separate directory or delete the old install directory and extract the new distro in that (now empty) original location.
Do not set rhq.autoinstall.database to the value of "overwrite" since this will purge all the RHQ data in the database and effectively make this a new, clean install and not a true upgrade. Only set this to overwrite if you truly want to start over with a completely clean and empty RHQ database.
Do make sure you set rhq.server.high-availability.name to the original server's name - that is, this should be the same server name of the server you are upgrading. If the previous installed server left this blank, you can leave this blank as well, but you must ensure that the hostname/domain of the machine has not changed. If that did change, you must explicitly put the old name of the server as the value of this property. If this name does not match the previous server's name, you will effectively be adding another server to the RHQ Server's HA Cloud, which is not what you want to do when simply upgrading an already existing server.
If you aren't sure what the name was, you can ask the installer to give you a list of all existing servers currently registered in the RHQ system. You do this via the --listservers (aka -l) command line option to the rhq-installer script: <rhq-install-dir>/bin/rhq-installer.[sh,bat] --listservers
There is a single file that you can use to configure the RHQ Server: <rhq-install-dir>/bin/rhq-server.properties. To change the configuration of the RHQ Server, you edit that file with the new values you want, shutdown the RHQ Server, then restart it.
Due to some limitations within JBoss AS7, there are some settings that will not take effect immediately upon restart. These are settings such as Tomcat security settings, the SMTP server hostname and the database username and password. The installer's --reconfig option is invoked by rhq-server.[sh,bat] whenever you start the server to attempt to reconfigure the server if changes are detected in the rhq-server.properties. When in doubt, after changing rhq-server.properties and restarting the RHQ Server, run the installer with the --reconfig command line option:
<rhq-install-dir>/bin/rhq-installer.[sh,bat] --reconfig